home *** CD-ROM | disk | FTP | other *** search
/ Cream of the Crop 25 / Cream of the Crop 25.iso / utility / ffe101.zip / GRAPH.SWG / 0001_BMP ICON RES EXPLANATION.pas next >
Pascal/Delphi Source File  |  1996-09-04  |  42KB  |  1,057 lines
  1. Graphics File Formats
  2.  
  3. This  topic  describes the graphics-file  formats  used by the Microsoft
  4. Windows   operating   system.  Graphics   files  include  bitmap  files,
  5. icon-resource files, and cursor-resource files.
  6.  
  7. Bitmap-File Formats
  8.  
  9. Windows  bitmap  files are stored  in  a device-independent bitmap (DIB)
  10. format  that allows Windows to display the bitmap on any type of display
  11. device.  The  term "device independent"  means that the bitmap specifies
  12. pixel  color  in a form independent of  the  method used by a display to
  13. represent color. The default filename extension of a Windows DIB file is
  14. .BMP.
  15.  
  16. Bitmap-File Structures
  17.  
  18. Each  bitmap  file contains a  bitmap-file  header, a bitmap-information
  19. header,  a  color table, and an array  of  bytes that defines the bitmap
  20. bits. The file has the following form:
  21.  
  22. BITMAPFILEHEADER bmfh;
  23. BITMAPINFOHEADER bmih;
  24. RGBQUAD          aColors[];
  25. BYTE             aBitmapBits[];
  26.  
  27. The  bitmap-file  header contains information  about the type, size, and
  28. layout  of a device-independent bitmap file.  The header is defined as a
  29. BITMAPFILEHEADER structure.
  30.  
  31. The  bitmap-information header, defined as a BITMAPINFOHEADER structure,
  32. specifies  the  dimensions, compression type,  and  color format for the
  33. bitmap.
  34.  
  35. The  color table, defined as an array of RGBQUAD structures, contains as
  36. many  elements as there are colors in the bitmap. The color table is not
  37. present for bitmaps with 24 color bits because each pixel is represented
  38. by  24-bit  red-green-blue (RGB) values in  the actual bitmap data area.
  39. The colors in the table should appear in order of importance. This helps
  40. a display driver render a bitmap on a device that cannot display as many
  41. colors  as there are in the bitmap. If the DIB is in Windows version 3.0
  42. or  later  format, the driver can  use  the biClrImportant member of the
  43. BITMAPINFOHEADER structure to determine which colors are important.
  44.  
  45. The   BITMAPINFO   structure  can  be   used  to  represent  a  combined
  46. bitmap-information  header and color table. The bitmap bits, immediately
  47. following   the  color  table,  consist  of  an  array  of  BYTE  values
  48. representing consecutive rows, or "scan lines," of the bitmap. Each scan
  49. line  consists of consecutive bytes representing  the pixels in the scan
  50. line,  in  left-to-right order. The number  of bytes representing a scan
  51. line  depends  on  the  color format and  the  width,  in pixels, of the
  52. bitmap. If necessary, a scan line must be zero-padded to end on a 32-bit
  53. boundary. However, segment boundaries can appear anywhere in the bitmap.
  54. The  scan lines in the bitmap are stored from bottom up. This means that
  55. the  first  byte  in the array  represents  the pixels in the lower-left
  56. corner  of  the  bitmap and the last  byte  represents the pixels in the
  57. upper-right corner.
  58.  
  59. The  biBitCount member of the  BITMAPINFOHEADER structure determines the
  60. number  of bits that define each pixel  and the maximum number of colors
  61. in the bitmap. These members can have any of the following values:
  62.  
  63. Value   Meaning
  64.  
  65. 1  Bitmap  is monochrome and the  color table contains two entries. Each
  66. bit  in  the bitmap array represents a  pixel.  If the bit is clear, the
  67. pixel is displayed with the color of the first entry in the color table.
  68. If  the  bit is set, the pixel has  the color of the second entry in the
  69. table.
  70.  
  71. 4  Bitmap  has  a  maximum of 16  colors.  Each  pixel  in the bitmap is
  72. represented  by a 4-bit index into the  color table. For example, if the
  73. first  byte  in the bitmap is 0x1F,  the byte represents two pixels. The
  74. first pixel contains the color in the second table entry, and the second
  75. pixel contains the color in the sixteenth table entry.
  76.  
  77. 8  Bitmap  has  a  maximum of 256  colors.  Each  pixel in the bitmap is
  78. represented  by a 1-byte index into the color table. For example, if the
  79. first  byte in the bitmap is 0x1F, the  first pixel has the color of the
  80. thirty-second table entry.
  81.  
  82. 24  Bitmap  has a maximum of  2^24 colors. The bmiColors (or bmciColors)
  83. member  is NULL, and each 3-byte sequence in the bitmap array represents
  84. the  relative  intensities of red, green,  and blue, respectively, for a
  85. pixel.
  86.  
  87. The  biClrUsed  member of the  BITMAPINFOHEADER  structure specifies the
  88. number  of color indexes in the color table actually used by the bitmap.
  89. If  the  biClrUsed  member is set to  zero,  the bitmap uses the maximum
  90. number of colors corresponding to the value of the biBitCount member. An
  91. alternative    form   of   bitmap    file   uses   the   BITMAPCOREINFO,
  92. BITMAPCOREHEADER, and RGBTRIPLE structures.
  93.  
  94. Bitmap Compression
  95.  
  96. Windows  versions 3.0 and later support run-length encoded (RLE) formats
  97. for  compressing bitmaps that use 4 bits per pixel and 8 bits per pixel.
  98. Compression reduces the disk and memory storage required for a bitmap.
  99.  
  100. Compression of 8-Bits-per-Pixel Bitmaps
  101.  
  102. When  the biCompression member of  the BITMAPINFOHEADER structure is set
  103. to  BI_RLE8, the DIB is compressed using a run-length encoded format for
  104. a  256-color  bitmap.  This  format uses  two  modes:  encoded  mode and
  105. absolute mode. Both modes can occur anywhere throughout a single bitmap.
  106.  
  107. Encoded Mode
  108.  
  109. A  unit of information in encoded mode  consists of two bytes. The first
  110. byte  specifies  the number of consecutive  pixels to be drawn using the
  111. color index contained in the second byte. The first byte of the pair can
  112. be set to zero to indicate an escape that denotes the end of a line, the
  113. end  of the bitmap, or a delta. The interpretation of the escape depends
  114. on  the value of the second byte of the pair, which must be in the range
  115. 0x00  through 0x02. Following are the meanings of the escape values that
  116. can be used in the second byte:
  117.  
  118. Second byte     Meaning
  119.  
  120. 0       End of line.
  121. 1       End of bitmap.
  122. 2  Delta.  The  two bytes following  the  escape contain unsigned values
  123. indicating  the  horizontal and vertical offsets  of the next pixel from
  124. the current position.
  125.  
  126. Absolute Mode
  127.  
  128. Absolute  mode  is signaled by the first  byte  in the pair being set to
  129. zero  and  the second byte to a  value between 0x03 and 0xFF. The second
  130. byte  represents the number of bytes that follow, each of which contains
  131. the  color  index of a single pixel. Each  run must be aligned on a word
  132. boundary.  Following is an example of an 8-bit RLE bitmap (the two-digit
  133. hexadecimal  values  in the second column  represent a color index for a
  134. single pixel):
  135.  
  136. Compressed data         Expanded data
  137.  
  138. 03 04                   04 04 04
  139. 05 06                   06 06 06 06 06
  140. 00 03 45 56 67 00       45 56 67
  141. 02 78                   78 78
  142. 00 02 05 01             Move 5 right and 1 down
  143. 02 78                   78 78
  144. 00 00                   End of line
  145. 09 1E                   1E 1E 1E 1E 1E 1E 1E 1E 1E
  146. 00 01                   End of RLE bitmap
  147.  
  148. Compression of 4-Bits-per-Pixel Bitmaps
  149.  
  150. When  the biCompression member of  the BITMAPINFOHEADER structure is set
  151. to  BI_RLE4, the DIB is compressed using a run-length encoded format for
  152. a 16-color bitmap. This format uses two modes: encoded mode and absolute
  153. mode.
  154.  
  155. Encoded Mode
  156.  
  157. A  unit of information in encoded mode  consists of two bytes. The first
  158. byte  of  the pair contains the number  of  pixels to be drawn using the
  159. color indexes in the second byte.
  160.  
  161. The second byte contains two color indexes, one in its high-order nibble
  162. (that is, its low-order 4 bits) and one in its low-order nibble.
  163.  
  164. The  first  pixel is drawn using  the  color specified by the high-order
  165. nibble, the second is drawn using the color in the low-order nibble, the
  166. third is drawn with the color in the high-order nibble, and so on, until
  167. all the pixels specified by the first byte have been drawn.
  168.  
  169. The first byte of the pair can be set to zero to indicate an escape that
  170. denotes  the  end  of  a line, the end  of  the  bitmap, or a delta. The
  171. interpretation  of the escape depends on the value of the second byte of
  172. the pair. In encoded mode, the second byte has a value in the range 0x00
  173. through  0x02. The meaning of these values is the same as for a DIB with
  174. 8 bits per pixel.
  175.  
  176. Absolute Mode
  177.  
  178. In absolute mode, the first byte contains zero, the second byte contains
  179. the  number  of color indexes that  follow, and subsequent bytes contain
  180. color  indexes in their high- and low-order nibbles, one color index for
  181. each pixel. Each run must be aligned on a word boundary.
  182.  
  183. Following is an example of a 4-bit RLE bitmap (the one-digit hexadecimal
  184. values in the second column represent a color index for a single pixel):
  185.  
  186. Compressed data         Expanded data
  187.  
  188. 03 04                   0 4 0
  189. 05 06                   0 6 0 6 0
  190. 00 06 45 56 67 00       4 5 5 6 6 7
  191. 04 78                   7 8 7 8
  192. 00 02 05 01             Move 5 right and 1 down
  193. 04 78                   7 8 7 8
  194. 00 00                   End of line
  195. 09 1E                   1 E 1 E 1 E 1 E 1
  196. 00 01                   End of RLE bitmap
  197.  
  198. Bitmap Example
  199.  
  200. The  following  example is a text dump  of a 16-color bitmap (4 bits per
  201. pixel):
  202.  
  203. Win3DIBFile
  204.               BitmapFileHeader
  205.                   Type       19778
  206.                   Size       3118
  207.                   Reserved1  0
  208.                   Reserved2  0
  209.                   OffsetBits 118
  210.               BitmapInfoHeader
  211.                   Size            40
  212.                   Width           80
  213.                   Height          75
  214.                   Planes          1
  215.                   BitCount        4
  216.                   Compression     0
  217.                   SizeImage       3000
  218.  
  219.                   XPelsPerMeter   0
  220.                   YPelsPerMeter   0
  221.                   ColorsUsed      16
  222.                   ColorsImportant 16
  223.               Win3ColorTable
  224.                   Blue  Green  Red  Unused
  225. [00000000]        84    252    84   0
  226. [00000001]        252   252    84   0
  227. [00000002]        84    84     252  0
  228. [00000003]        252   84     252  0
  229. [00000004]        84    252    252  0
  230. [00000005]        252   252    252  0
  231. [00000006]        0     0      0    0
  232. [00000007]        168   0      0    0
  233. [00000008]        0     168    0    0
  234. [00000009]        168   168    0    0
  235. [0000000A]        0     0      168  0
  236. [0000000B]        168   0      168  0
  237. [0000000C]        0     168    168  0
  238. [0000000D]        168   168    168  0
  239. [0000000E]        84    84     84   0
  240. [0000000F]        252   84     84   0
  241.               Image
  242.     .
  243.     .                                           Bitmap data
  244.     .
  245.  
  246. Icon-Resource File Format
  247.  
  248. An  icon-resource  file  contains image data  for  icons used by Windows
  249. applications.  The  file consists of  an  icon directory identifying the
  250. number  and  types  of icon images in  the  file,  plus one or more icon
  251. images.  The  default  filename extension  for  an icon-resource file is
  252. .ICO.
  253.  
  254. Icon Directory
  255.  
  256. Each  icon-resource  file  starts  with  an  icon  directory.  The  icon
  257. directory,  defined  as  an ICONDIR  structure,  specifies the number of
  258. icons  in the resource and the dimensions  and color format of each icon
  259. image. The ICONDIR structure has the following form:
  260.  
  261. typedef struct ICONDIR {
  262.     WORD          idReserved;
  263.     WORD          idType;
  264.     WORD          idCount;
  265.     ICONDIRENTRY  idEntries[1];
  266. } ICONHEADER;
  267.  
  268. Following are the members in the ICONDIR structure:
  269.  
  270. idReserved      Reserved; must be zero.
  271. idType          Specifies the resource type. This member is set to 1.
  272. idCount         Specifies the number of entries in the directory.
  273. idEntries       Specifies an array of ICONDIRENTRY structures containing
  274. information about individual icons. The idCount member specifies the number
  275. of structures in the array.
  276.  
  277. The ICONDIRENTRY structure specifies the dimensions and color format for
  278. an icon. The structure has the following form:
  279.  
  280.  
  281.  
  282. struct IconDirectoryEntry {
  283.     BYTE  bWidth;
  284.     BYTE  bHeight;
  285.     BYTE  bColorCount;
  286.     BYTE  bReserved;
  287.     WORD  wPlanes;
  288.     WORD  wBitCount;
  289.     DWORD dwBytesInRes;
  290.     DWORD dwImageOffset;
  291. };
  292.  
  293. Following are the members in the ICONDIRENTRY structure:
  294.  
  295. bWidth Specifies the width of the icon, in pixels. Acceptable values are
  296. 16, 32, and 64.
  297.  
  298. bHeight  Specifies the height of the  icon, in pixels. Acceptable values
  299. are 16, 32, and 64.
  300.  
  301. bColorCount  Specifies  the  number of  colors  in  the icon. Acceptable
  302. values are 2, 8, and 16.
  303.  
  304. bReserved       Reserved; must be zero.
  305. wPlanes         Specifies the number of color planes in the icon bitmap.
  306. wBitCount       Specifies the number of bits in the icon bitmap.
  307. dwBytesInRes    Specifies the size of the resource, in bytes.
  308. dwImageOffset   Specifies the offset, in bytes, from the beginning of the
  309. file to the icon image.
  310.  
  311. Icon Image
  312.  
  313. Each   icon-resource  file  contains  one  icon  image  for  each  image
  314. identified  in  the  icon  directory.  An  icon  image  consists  of  an
  315. icon-image header, a color table, an XOR mask, and an AND mask. The icon
  316. image has the following form:
  317.  
  318.  
  319.  
  320. BITMAPINFOHEADER    icHeader;
  321. RGBQUAD             icColors[];
  322. BYTE                icXOR[];
  323. BYTE                icAND[];
  324.  
  325. The   icon-image  header,  defined   as  a  BITMAPINFOHEADER  structure,
  326. specifies  the dimensions and color format  of the icon bitmap. Only the
  327. biSize  through biBitCount members and  the biSizeImage member are used.
  328. All other members (such as biCompression and biClrImportant) must be set
  329. to zero.
  330.  
  331. The  color  table, defined as an  array of RGBQUAD structures, specifies
  332. the  colors  used in the XOR mask. As  with  the color table in a bitmap
  333. file,  the  biBitCount  member in  the  icon-image header determines the
  334. number  of  elements in the array.  For more information about the color
  335. table, see Section 1.1, "Bitmap-File Formats."
  336.  
  337. The XOR mask, immediately following the color table, is an array of BYTE
  338. values representing consecutive rows of a bitmap. The bitmap defines the
  339. basic  shape  and color of the icon image.  As with the bitmap bits in a
  340. bitmap  file,  the bitmap data in  an icon-resource file is organized in
  341. scan  lines, with each byte representing  one or more pixels, as defined
  342. by  the color format. For more  information about these bitmap bits, see
  343. Section 1.1, "Bitmap-File Formats."
  344.  
  345. The  AND  mask, immediately following the XOR  mask, is an array of BYTE
  346. values,  representing a monochrome bitmap with the same width and height
  347. as  the  XOR mask. The array is  organized in scan lines, with each byte
  348. representing 8 pixels.
  349.  
  350. When Windows draws an icon, it uses the AND and XOR masks to combine the
  351. icon image with the pixels already on the display surface. Windows first
  352. applies the AND mask by using a bitwise AND operation; this preserves or
  353. removes existing pixel color. Windows then applies the XOR mask by using
  354. a bitwise XOR operation. This sets the final color for each pixel.
  355.  
  356. The  following  illustration shows the XOR  and  AND masks that create a
  357. monochrome  icon  (measuring  8 pixels by 8  pixels)  in  the form of an
  358. uppercase K:
  359.  
  360. Windows Icon Selection
  361.  
  362. Windows  detects  the resolution of the  current  display and matches it
  363. against  the  width  and height specified  for  each version of the icon
  364. image.  If  Windows determines that there  is  an exact match between an
  365. icon  image  and  the  current  device,  it  uses  the  matching  image.
  366. Otherwise,  it selects the closest match  and stretches the image to the
  367. proper size.
  368.  
  369. If  an icon-resource file contains more  than one image for a particular
  370. resolution,  Windows  uses the icon image  that most closely matches the
  371. color  capabilities  of  the current display.  If  no  image matches the
  372. device  capabilities  exactly,  Windows selects  the  image that has the
  373. greatest  number  of  colors  without  exceeding  the  number of display
  374. colors.  If  all  images exceed the  color  capabilities  of the current
  375. display, Windows uses the icon image with the least number of colors.
  376.  
  377.  
  378.  
  379. Cursor-Resource File Format
  380.  
  381. A  cursor-resource file contains image data  for cursors used by Windows
  382. applications.  The  file consists of  a cursor directory identifying the
  383. number  and types of cursor images in  the file, plus one or more cursor
  384. images.  The  default filename extension  for  a cursor-resource file is
  385. .CUR.
  386.  
  387. Cursor Directory
  388.  
  389. Each  cursor-resource  file starts with  a  cursor directory. The cursor
  390. directory,  defined  as a CURSORDIR  structure,  specifies the number of
  391. cursors  in the file and the dimensions  and color format of each cursor
  392. image. The CURSORDIR structure has the following form:
  393.  
  394.  
  395. typedef struct _CURSORDIR {
  396.     WORD           cdReserved;
  397.     WORD           cdType;
  398.     WORD           cdCount;
  399.     CURSORDIRENTRY cdEntries[];
  400. } CURSORDIR;
  401.  
  402. Following are the members in the CURSORDIR structure:
  403.  
  404. cdReserved      Reserved; must be zero.
  405. cdType          Specifies the resource type. This member must be set to 2.
  406. cdCount         Specifies the number of cursors in the file.
  407. cdEntries       Specifies an array of CURSORDIRENTRY structures containing
  408. information about individual cursors. The cdCount member specifies the number
  409. of structures in the array.
  410.  
  411. A  CURSORDIRENTRY structure specifies the dimensions and color format of
  412. a cursor image. The structure has the following form:
  413.  
  414.  
  415.  
  416. typedef struct _CURSORDIRENTRY {
  417.     BYTE  bWidth;
  418.     BYTE  bHeight;
  419.     BYTE  bColorCount;
  420.     BYTE  bReserved;
  421.     WORD  wXHotspot;
  422.     WORD  wYHotspot;
  423.     DWORD lBytesInRes;
  424.     DWORD dwImageOffset;
  425. } CURSORDIRENTRY;
  426.  
  427. Following are the members in the CURSORDIRENTRY structure:
  428.  
  429. bWidth          Specifies the width of the cursor, in pixels.
  430. bHeight         Specifies the height of the cursor, in pixels.
  431. bColorCount     Reserved; must be zero.
  432. bReserved       Reserved; must be zero.
  433. wXHotspot       Specifies the x-coordinate, in pixels, of the hot spot.
  434. wYHotspot       Specifies the y-coordinate, in pixels, of the hot spot.
  435. lBytesInRes     Specifies the size of the resource, in bytes.
  436. dwImageOffset   Specifies the offset, in bytes, from the start of the file to
  437. the cursor image.
  438.  
  439. Cursor Image
  440.  
  441. Each  cursor-resource  file  contains one  cursor  image  for each image
  442. identified  in  the  cursor  directory. A  cursor  image  consists  of a
  443. cursor-image  header,  a color table, an XOR  mask, and an AND mask. The
  444. cursor image has the following form:
  445.  
  446.  
  447.  
  448. BITMAPINFOHEADER    crHeader;
  449. RGBQUAD             crColors[];
  450. BYTE                crXOR[];
  451. BYTE                crAND[];
  452.  
  453. The  cursor hot spot is a single pixel in the cursor bitmap that Windows
  454. uses  to track the cursor. The crXHotspot and crYHotspot members specify
  455. the  x- and y-coordinates of the  cursor hot spot. These coordinates are
  456. 16-bit integers.
  457.  
  458. The  cursor-image  header,  defined  as  a  BITMAPINFOHEADER  structure,
  459. specifies the dimensions and color format of the cursor bitmap. Only the
  460. biSize  through biBitCount members and  the biSizeImage member are used.
  461. The  biHeight  member specifies the combined  height  of the XOR and AND
  462. masks  for  the cursor. This value is  twice the height of the XOR mask.
  463. The  biPlanes and biBitCount members must  be 1. All other members (such
  464. as biCompression and biClrImportant) must be set to zero.
  465.  
  466. The  color  table, defined as an  array of RGBQUAD structures, specifies
  467. the  colors used in the XOR mask. For a cursor image, the table contains
  468. exactly  two structures, since the biBitCount member in the cursor-image
  469. header is always 1.
  470.  
  471. The XOR mask, immediately following the color table, is an array of BYTE
  472. values representing consecutive rows of a bitmap. The bitmap defines the
  473. basic  shape and color of the cursor image. As with the bitmap bits in a
  474. bitmap  file, the bitmap data in  a cursor-resource file is organized in
  475. scan  lines, with each byte representing  one or more pixels, as defined
  476. by  the color format. For more  information about these bitmap bits, see
  477. Section 1.1, "Bitmap-File Formats."
  478.  
  479. The  AND  mask, immediately following the XOR  mask, is an array of BYTE
  480. values  representing a monochrome bitmap with  the same width and height
  481. as  the  XOR mask. The array is  organized in scan lines, with each byte
  482. representing 8 pixels.
  483.  
  484. When  Windows  draws a cursor, it uses  the AND and XOR masks to combine
  485. the cursor image with the pixels already on the display surface. Windows
  486. first  applies  the  AND  mask by  using  a  bitwise AND operation; this
  487. preserves  or removes existing pixel color.  Window then applies the XOR
  488. mask  by  using a bitwise XOR operation.  This  sets the final color for
  489. each pixel.
  490.  
  491. The following illustration shows the XOR and the AND masks that create a
  492. cursor (measuring 8 pixels by 8 pixels) in the form of an arrow:
  493.  
  494. Following  are  the bit-mask values  necessary  to produce black, white,
  495. inverted, and transparent results:
  496.  
  497. Pixel result    AND maskXOR mask
  498.  
  499. Black           0               0
  500. White           0               1
  501. Transparent     1               0
  502. Inverted1               1
  503.  
  504. Windows Cursor Selection
  505.  
  506. If  a cursor-resource file contains more  than one cursor image, Windows
  507. determines  the  best  match for a  particular  display by examining the
  508. width and height of the cursor images.
  509.  
  510.  
  511. ==============================================================================
  512.  
  513.  
  514. BITMAPFILEHEADER (3.0)
  515.  
  516.  
  517.  
  518. typedef struct tagBITMAPFILEHEADER {    /* bmfh */
  519.     UINT    bfType;
  520.     DWORD   bfSize;
  521.     UINT    bfReserved1;
  522.     UINT    bfReserved2;
  523.     DWORD   bfOffBits;
  524. } BITMAPFILEHEADER;
  525.  
  526. The  BITMAPFILEHEADER  structure  contains  information  about the type,
  527. size, and layout of a device-independent bitmap (DIB) file.
  528.  
  529. Member          Description
  530.  
  531. bfType          Specifies the type of file. This member must be BM.
  532. bfSize          Specifies the size of the file, in bytes.
  533. bfReserved1     Reserved; must be set to zero.
  534. bfReserved2     Reserved; must be set to zero.
  535. bfOffBits  Specifies the byte offset from the BITMAPFILEHEADER structure
  536. to the actual bitmap data in the file.
  537.  
  538. Comments
  539.  
  540. A BITMAPINFO or BITMAPCOREINFO structure immediately follows the
  541. BITMAPFILEHEADER structure in the DIB file.
  542.  
  543. See Also
  544.  
  545. BITMAPCOREINFO, BITMAPINFO
  546.  
  547.  
  548. ==============================================================================
  549. BITMAPINFO (3.0)
  550.  
  551.  
  552.  
  553. typedef struct tagBITMAPINFO {  /* bmi */
  554.     BITMAPINFOHEADER    bmiHeader;
  555.     RGBQUAD             bmiColors[1];
  556. } BITMAPINFO;
  557.  
  558. The   BITMAPINFO  structure  fully  defines  the  dimensions  and  color
  559. information for a Windows 3.0 or later device-independent bitmap (DIB).
  560.  
  561. Member          Description
  562.  
  563. bmiHeader       Specifies a BITMAPINFOHEADER structure that contains
  564. information about the dimensions and color format of a DIB.
  565.  
  566. bmiColors  Specifies  an  array of  RGBQUAD  structures  that define the
  567. colors in the bitmap.
  568.  
  569. Comments
  570.  
  571. A  Windows 3.0 or later DIB consists of two distinct parts: a BITMAPINFO
  572. structure,  which describes the dimensions and colors of the bitmap, and
  573. an  array  of bytes defining the pixels  of  the bitmap. The bits in the
  574. array are packed together, but each scan line must be zero-padded to end
  575. on  a LONG boundary. Segment boundaries, however, can appear anywhere in
  576. the bitmap. The origin of the bitmap is the lower-left corner.
  577.  
  578. The  biBitCount member of the  BITMAPINFOHEADER structure determines the
  579. number  of bits which define each pixel and the maximum number of colors
  580. in the bitmap. This member may be set to any of the following values:
  581.  
  582. Value   Meaning
  583.  
  584. 1  The bitmap is monochrome, and  the bmciColors member must contain two
  585. entries.  Each bit in the bitmap array represents a pixel. If the bit is
  586. clear,  the pixel is displayed with the  color of the first entry in the
  587. bmciColors  table.  If  the bit is set,  the  pixel has the color of the
  588. second entry in the table.
  589.  
  590. 4  The  bitmap  has a maximum of  16  colors,  and the bmciColors member
  591. contains  16  entries.  Each  pixel in  the  bitmap  is represented by a
  592. four-bit index into the color table.
  593.  
  594. For  example,  if  the  first  byte in  the  bitmap  is  0x1F,  the byte
  595. represents  two pixels. The first pixel contains the color in the second
  596. table  entry,  and the second pixel  contains the color in the sixteenth
  597. table entry.
  598.  
  599. 8  The  bitmap  has a maximum of  256  colors, and the bmciColors member
  600. contains  256 entries. In this case, each byte in the array represents a
  601. single pixel.
  602.  
  603. 24  The  bitmap has a maximum of  2^24  colors. The bmciColors member is
  604. NULL,  and  each  3-byte  sequence in  the  bitmap  array represents the
  605. relative intensities of red, green, and blue, respectively, of a pixel.
  606.  
  607. The  biClrUsed  member of the  BITMAPINFOHEADER  structure specifies the
  608. number  of color indexes in the color table actually used by the bitmap.
  609. If  the  biClrUsed  member is set to  zero,  the bitmap uses the maximum
  610. number of colors corresponding to the value of the biBitCount member.
  611.  
  612. The  colors in the bmiColors table should appear in order of importance.
  613. Alternatively,  for functions that use DIBs, the bmiColors member can be
  614. an  array  of  16-bit unsigned integers  that  specify an index into the
  615. currently  realized  logical palette instead  of explicit RGB values. In
  616. this  case, an application using the bitmap must call DIB functions with
  617. the wUsage parameter set to DIB_PAL_COLORS.
  618.  
  619. Note:  The  bmiColors member should not  contain  palette indexes if the
  620. bitmap  is to be stored in a file or transferred to another application.
  621. Unless  the  application  uses  the  bitmap  exclusively  and  under its
  622. complete  control,  the bitmap color  table  should contain explicit RGB
  623. values.
  624.  
  625. See Also
  626.  
  627. BITMAPINFOHEADER, RGBQUAD
  628.  
  629. ==============================================================================
  630. BITMAPINFOHEADER (3.0)
  631.  
  632.  
  633.  
  634. typedef struct tagBITMAPINFOHEADER {    /* bmih */
  635.     DWORD   biSize;
  636.     LONG    biWidth;
  637.     LONG    biHeight;
  638.     WORD    biPlanes;
  639.     WORD    biBitCount;
  640.     DWORD   biCompression;
  641.     DWORD   biSizeImage;
  642.     LONG    biXPelsPerMeter;
  643.     LONG    biYPelsPerMeter;
  644.     DWORD   biClrUsed;
  645.     DWORD   biClrImportant;
  646. } BITMAPINFOHEADER;
  647.  
  648. The BITMAPINFOHEADER structure contains information about the dimensions
  649. and  color  format of a Windows  3.0  or later device-independent bitmap
  650. (DIB).
  651.  
  652. Member          Description
  653.  
  654. biSize          Specifies the number of bytes required by the
  655. BITMAPINFOHEADER structure.
  656.  
  657. biWidth         Specifies the width of the bitmap, in pixels.
  658. biHeightSpecifies the height of the bitmap, in pixels.
  659.  
  660. biPlanesSpecifies the number of planes for the target device. This
  661. member must be set to 1.
  662.  
  663. biBitCount      Specifies the number of bits per pixel. This value must be 1,
  664. 4, 8, or 24.
  665.  
  666. biCompression   Specifies the type of compression for a compressed bitmap. It
  667. can be one of the following values:
  668.  
  669. Value           Meaning
  670.  
  671. BI_RGB          Specifies that the bitmap is not compressed.
  672.  
  673. BI_RLE8  Specifies  a run-length encoded format  for bitmaps with 8 bits
  674. per  pixel.  The compression format is  a  2-byte format consisting of a
  675. count  byte  followed  by  a byte  containing  a  color  index. For more
  676. information, see the following Comments section.
  677.  
  678. BI_RLE4  Specifies  a run-length encoded format  for bitmaps with 4 bits
  679. per  pixel.  The compression format is  a  2-byte format consisting of a
  680. count   byte  followed  by  two  word-length  color  indexes.  For  more
  681. information, see the following Comments section.
  682.  
  683. biSizeImage  Specifies the size, in bytes, of  the image. It is valid to
  684. set this member to zero if the bitmap is in the BI_RGB format.
  685.  
  686. biXPelsPerMeter  Specifies  the  horizontal  resolution,  in  pixels per
  687. meter,  of the target device for the bitmap. An application can use this
  688. value  to  select a bitmap from a  resource  group that best matches the
  689. characteristics of the current device.
  690.  
  691. biYPelsPerMeter  Specifies the vertical resolution, in pixels per meter,
  692. of the target device for the bitmap.
  693.  
  694. biClrUsed  Specifies  the  number of color  indexes  in  the color table
  695. actually  used by the bitmap. If this value is zero, the bitmap uses the
  696. maximum  number  of colors corresponding to  the value of the biBitCount
  697. member.  For  more information on the  maximum sizes of the color table,
  698. see the description of the BITMAPINFO structure earlier in this topic.
  699.  
  700. If  the  biClrUsed member is nonzero,  it specifies the actual number of
  701. colors  that  the  graphics engine or  device  driver will access if the
  702. biBitCount member is less than 24. If biBitCount is set to 24, biClrUsed
  703. specifies  the  size  of  the reference  color  table  used  to optimize
  704. performance  of Windows color palettes. If the bitmap is a packed bitmap
  705. (that  is,  a bitmap in which  the  bitmap array immediately follows the
  706. BITMAPINFO  header  and  which is referenced  by  a single pointer), the
  707. biClrUsed  member must be set to zero or to the actual size of the color
  708. table.
  709.  
  710. biClrImportant Specifies the number of color indexes that are considered
  711. important  for displaying the bitmap. If  this value is zero, all colors
  712. are important.
  713.  
  714. Comments
  715.  
  716. The  BITMAPINFO structure combines the  BITMAPINFOHEADER structure and a
  717. color  table  to  provide a complete  definition  of  the dimensions and
  718. colors  of  a  Windows  3.0 or  later  DIB.  For  more information about
  719. specifying  a  Windows  3.0 DIB, see  the  description of the BITMAPINFO
  720. structure.
  721.  
  722. An application should use the information stored in the biSize member to
  723. locate the color table in a BITMAPINFO structure as follows:
  724.  
  725. pColor = ((LPSTR) pBitmapInfo + (WORD) (pBitmapInfo->bmiHeader.biSize))
  726.  
  727. Windows  supports  formats  for compressing  bitmaps  that  define their
  728. colors  with  8  bits per pixel and  with  4 bits per pixel. Compression
  729. reduces  the  disk  and  memory storage  required  for  the  bitmap. The
  730. following paragraphs describe these formats.
  731.  
  732. BI_RLE8
  733.  
  734. When  the  biCompression  member  is  set  to  BI_RLE8,  the  bitmap  is
  735. compressed  using a run-length encoding format for an 8-bit bitmap. This
  736. format  may be compressed in either  of two modes: encoded and absolute.
  737. Both modes can occur anywhere throughout a single bitmap.
  738.  
  739. Encoded  mode consists of two bytes: the first byte specifies the number
  740. of consecutive pixels to be drawn using the color index contained in the
  741. second  byte. In addition, the first byte of the pair can be set to zero
  742. to  indicate an escape that denotes an end  of line, end of bitmap, or a
  743. delta.  The  interpretation  of the escape  depends  on the value of the
  744. second  byte  of the pair. The following  list  shows the meaning of the
  745. second byte:
  746.  
  747. Value   Meaning
  748.  
  749. 0       End of line.
  750. 1       End of bitmap.
  751. 2       Delta. The two bytes following the escape contain unsigned values
  752. indicating the horizontal and vertical offset of the next pixel from the
  753. current position.
  754.  
  755. Absolute  mode is signaled by the first  byte set to zero and the second
  756. byte  set to a value between 0x03 and 0xFF. In absolute mode, the second
  757. byte  represents the number of bytes that follow, each of which contains
  758. the  color index of a single pixel. When  the second byte is set to 2 or
  759. less,  the  escape has the same meaning  as in encoded mode. In absolute
  760. mode, each run must be aligned on a word boundary. The following example
  761. shows the hexadecimal values of an 8-bit compressed bitmap:
  762.  
  763.  
  764.  
  765. 03 04 05 06 00 03 45 56 67 00 02 78 00 02 05 01
  766. 02 78 00 00 09 1E 00 01
  767.  
  768. This  bitmap would expand as follows (two-digit values represent a color
  769. index for a single pixel):
  770.  
  771.  
  772.  
  773. 04 04 04
  774. 06 06 06 06 06
  775. 45 56 67
  776. 78 78
  777. move current position 5 right and 1 down
  778. 78 78
  779. end of line
  780. 1E 1E 1E 1E 1E 1E 1E 1E 1E
  781. end of RLE bitmap
  782.  
  783. BI_RLE4
  784.  
  785. When  the  biCompression  member  is  set  to  BI_RLE4,  the  bitmap  is
  786. compressed  using a run-length encoding (RLE) format for a 4-bit bitmap,
  787. which  also uses encoded and absolute  modes. In encoded mode, the first
  788. byte  of  the pair contains the number  of  pixels to be drawn using the
  789. color  indexes  in the second byte.  The  second byte contains two color
  790. indexes, one in its high-order nibble (that is, its low-order four bits)
  791. and  one in its low-order nibble. The first of the pixels is drawn using
  792. the  color specified by the high-order nibble, the second is drawn using
  793. the  color in the low-order nibble, the third is drawn with the color in
  794. the  high-order nibble, and so on, until all the pixels specified by the
  795. first  byte  have been drawn. In  absolute mode, the first byte contains
  796. zero,  the second byte contains the number of color indexes that follow,
  797. and  subsequent bytes contain color indexes in their high- and low-order
  798. nibbles, one color index for each pixel. In absolute mode, each run must
  799. be aligned on a word boundary. The end-of-line, end-of-bitmap, and delta
  800. escapes also apply to BI_RLE4.
  801.  
  802. The following example shows the hexadecimal values of a 4-bit compressed
  803. bitmap:
  804.  
  805.  
  806.  
  807. 03 04 05 06 00 06 45 56 67 00 04 78 00 02 05 01
  808. 04 78 00 00 09 1E 00 01
  809.  
  810. This  bitmap  would expand as  follows  (single-digit values represent a
  811. color index for a single pixel):
  812.  
  813.  
  814.  
  815. 0 4 0
  816. 0 6 0 6 0
  817. 4 5 5 6 6 7
  818. 7 8 7 8
  819. move current position 5 right and 1 down
  820. 7 8 7 8
  821. end of line
  822. 1 E 1 E 1 E 1 E 1
  823. end of RLE bitmap
  824.  
  825. See Also
  826.  
  827. BITMAPINFO
  828.  
  829. ==============================================================================
  830. RGBQUAD (3.0)
  831.  
  832.  
  833.  
  834. typedef struct tagRGBQUAD {     /* rgbq */
  835.     BYTE    rgbBlue;
  836.     BYTE    rgbGreen;
  837.     BYTE    rgbRed;
  838.     BYTE    rgbReserved;
  839. } RGBQUAD;
  840.  
  841. The   RGBQUAD  structure  describes  a   color  consisting  of  relative
  842. intensities  of  red,  green,  and blue.  The  bmiColors  member  of the
  843. BITMAPINFO structure consists of an array of RGBQUAD structures.
  844.  
  845. Member          Description
  846.  
  847. rgbBlue         Specifies the intensity of blue in the color.
  848. rgbGreenSpecifies the intensity of green in the color.
  849. rgbRed          Specifies the intensity of red in the color.
  850. rgbReserved     Not used; must be set to zero.
  851.  
  852. See Also
  853.  
  854. BITMAPINFO
  855.  
  856. ==============================================================================
  857. RGB (2.x)
  858.  
  859. COLORREF RGB(cRed, cGreen, cBlue)
  860.  
  861. BYTE cRed;      /* red component of color       */
  862. BYTE cGreen;    /* green component of color     */
  863. BYTE cBlue;     /* blue component of color      */
  864.  
  865.  
  866. The  RGB macro selects an RGB color based on the parameters supplied and
  867. the color capabilities of the output device.
  868.  
  869. Parameter       Description
  870.  
  871. cRed    Specifies the intensity of the red color field.
  872. cGreen  Specifies the intensity of the green color field.
  873. cBlue   Specifies the intensity of the blue color field.
  874.  
  875. Returns
  876.  
  877. The return value specifies the resultant RGB color.
  878.  
  879. Comments
  880.  
  881. The  intensity  for each argument can range  from  0 through 255. If all
  882. three  intensities  are specified as zero,  the  result is black. If all
  883. three intensities are specified as 255, the result is white.
  884.  
  885. Comments
  886.  
  887. The RGB macro is defined in WINDOWS.H as follows:
  888.  
  889.  
  890.  
  891. #define RGB(r,g,b)   ((COLORREF)(((BYTE)(r)|((WORD)(g)<<8))| \
  892.     (((DWORD)(BYTE)(b))<<16)))
  893.  
  894. See Also
  895.  
  896. GetBValue, GetGValue, GetRValue, PALETTEINDEX, PALETTERGB
  897.  
  898. ==============================================================================
  899. BITMAPCOREINFO (3.0)
  900.  
  901.  
  902.  
  903. typedef struct tagBITMAPCOREINFO {  /* bmci */
  904.     BITMAPCOREHEADER bmciHeader;
  905.     RGBTRIPLE        bmciColors[1];
  906. } BITMAPCOREINFO;
  907.  
  908. The  BITMAPCOREINFO  structure  fully defines  the  dimensions and color
  909. information  for a device-independent bitmap (DIB). Windows applications
  910. should  use the BITMAPINFO structure  instead of BITMAPCOREINFO whenever
  911. possible.
  912.  
  913. Member          Description
  914.  
  915. bmciHeader      Specifies a BITMAPCOREHEADER structure that contains
  916. information about the dimensions and color format of a DIB.
  917.  
  918. bmciColors      Specifies an array of RGBTRIPLE structures that define the
  919. colors in the bitmap.
  920.  
  921. Comments
  922.  
  923. The  BITMAPCOREINFO  structure describes the  dimensions and colors of a
  924. bitmap.  It is followed immediately in memory by an array of bytes which
  925. define  the  pixels  of  the bitmap. The  bits  in  the array are packed
  926. together,  but  each  scan  line must be  zero-padded  to  end on a LONG
  927. boundary.  Segment  boundaries,  however,  can  appear  anywhere  in the
  928. bitmap. The origin of the bitmap is the lower-left corner.
  929.  
  930. The  bcBitCount member of the  BITMAPCOREHEADER structure determines the
  931. number  of bits that define each pixel  and the maximum number of colors
  932. in the bitmap. This member may be set to any of the following values:
  933.  
  934. Value   Meaning
  935.  
  936. 1  The bitmap is monochrome, and  the bmciColors member must contain two
  937. entries.  Each bit in the bitmap array represents a pixel. If the bit is
  938. clear,  the pixel is displayed with the  color of the first entry in the
  939. bmciColors  table.  If  the bit is set,  the  pixel has the color of the
  940. second entry in the table.
  941.  
  942. 4  The  bitmap  has a maximum of  16  colors,  and the bmciColors member
  943. contains  16  entries.  Each  pixel in  the  bitmap  is represented by a
  944. four-bit index into the color table.
  945.  
  946. For  example,  if  the  first  byte in  the  bitmap  is  0x1F,  the byte
  947. represents  two pixels. The first pixel contains the color in the second
  948. table  entry,  and the second pixel  contains the color in the sixteenth
  949. table entry.
  950.  
  951. 8  The  bitmap  has a maximum of  256  colors, and the bmciColors member
  952. contains  256 entries. In this case, each byte in the array represents a
  953. single pixel.
  954.  
  955. 24  The  bitmap has a maximum of  2^24  colors. The bmciColors member is
  956. NULL,  and  each  3-byte  sequence in  the  bitmap  array represents the
  957. relative intensities of red, green, and blue, respectively, of a pixel.
  958.  
  959. The colors in the bmciColors table should appear in order of importance.
  960. Alternatively, for functions that use DIBs, the bmciColors member can be
  961. an  array  of  16-bit unsigned integers  that  specify an index into the
  962. currently  realized  logical palette instead  of explicit RGB values. In
  963. this  case, an application using the bitmap must call DIB functions with
  964. the wUsage parameter set to DIB_PAL_COLORS.
  965.  
  966. Note:  The  bmciColors member should not  contain palette indexes if the
  967. bitmap  is to be stored in a file or transferred to another application.
  968. Unless  the  application  uses  the  bitmap  exclusively  and  under its
  969. complete  control,  the bitmap color  table  should contain explicit RGB
  970. values.
  971.  
  972. See Also
  973.  
  974. BITMAPINFO, BITMAPCOREHEADER, RGBTRIPLE
  975.  
  976.  
  977. ==============================================================================
  978. BITMAPCOREHEADER (3.0)
  979.  
  980.  
  981.  
  982. typedef struct tagBITMAPCOREHEADER {    /* bmch */
  983.     DWORD   bcSize;
  984.     short   bcWidth;
  985.     short   bcHeight;
  986.     WORD    bcPlanes;
  987.     WORD    bcBitCount;
  988. } BITMAPCOREHEADER;
  989.  
  990. The BITMAPCOREHEADER structure contains information about the dimensions
  991. and   color  format  of  a   device-independent  bitmap  (DIB).  Windows
  992. applications  should  use  the  BITMAPINFOHEADER  structure  instead  of
  993. BITMAPCOREHEADER whenever possible.
  994.  
  995. Member          Description
  996.  
  997. bcSize          Specifies the number of bytes required by the
  998. BITMAPCOREHEADER structure.
  999.  
  1000. bcWidth         Specifies the width of the bitmap, in pixels.
  1001. bcHeightSpecifies the height of the bitmap, in pixels.
  1002.  
  1003. bcPlanesSpecifies the number of planes for the target device. This
  1004. member must be set to 1.
  1005.  
  1006. bcBitCount      Specifies the number of bits per pixel. This value must be 1,
  1007. 4, 8, or 24.
  1008.  
  1009. Comments
  1010.  
  1011. The BITMAPCOREINFO structure combines the BITMAPCOREHEADER structure and
  1012. a  color  table to provide a  complete  definition of the dimensions and
  1013. colors of a DIB. See the description of the BITMAPCOREINFO structure for
  1014. more information about specifying a DIB.
  1015.  
  1016. An application should use the information stored in the bcSize member to
  1017. locate  the color table in a BITMAPCOREINFO structure with a method such
  1018. as the following:
  1019.  
  1020.  
  1021.  
  1022. lpColor = ((LPSTR) pBitmapCoreInfo + (UINT) (pBitmapCoreInfo->bcSize))
  1023.  
  1024. See Also
  1025.  
  1026. BITMAPCOREINFO, BITMAPINFOHEADER, BITMAPINFOHEADER
  1027.  
  1028. =============================================================================
  1029. RGBTRIPLE (3.0)
  1030.  
  1031.  
  1032.  
  1033. typedef struct tagRGBTRIPLE {   /* rgbt */
  1034.     BYTE    rgbtBlue;
  1035.     BYTE    rgbtGreen;
  1036.     BYTE    rgbtRed;
  1037. } RGBTRIPLE;
  1038.  
  1039. The  RGBTRIPLE  structure  describes  a  color  consisting  of  relative
  1040. intensities  of  red,  green,  and blue.  The  bmciColors  member of the
  1041. BITMAPCOREINFO  structure consists of an  array of RGBTRIPLE structures.
  1042. Windows  applications  should  use the  BITMAPINFO  structure instead of
  1043. BITMAPCOREINFO  whenever  possible.  The  BITMAPINFO  structure  uses an
  1044. RGBQUAD structure instead of the RGBTRIPLE structure.
  1045.  
  1046. Member  Description
  1047.  
  1048. rgbtBlueSpecifies the intensity of blue in the color.
  1049. rgbtGreen       Specifies the intensity of green in the color.
  1050. rgbtRed         Specifies the intensity of red in the color.
  1051.  
  1052. See Also
  1053.  
  1054. BITMAPCOREINFO, BITMAPINFO, RGBQUAD
  1055.  
  1056. ==============================================================================
  1057.